Gloss | |
| To view this file with Gloss-style markdown applied, you can double-click on the HTML version "Gloss.html" in IntraMine's Documentation folder, or click on the '?' in the navigation bar and then click on "Gloss.txt" listed there. For the plain text source, open Documentation/Gloss.txt in a text editor. | |
| In general, to view the HTML version of a .txt file that's been marked up with Gloss: | |
• open it using IntraMine's Viewer (in a result on the Search page, or a link on the Files page, or a link in a source or text file displayed by IntraMine's Viewer or Editor) | |
• convert the .txt file to .html using the Glosser service | |
• or convert using the supplied gloss2html.pl Perl program. | |
| NOTE: "tricks" such as zero width spaces, fat asterisks ✱, and images are used to avoid Gloss processing below, so you can see the original text followed by how Gloss renders it. | |
Overview | |
| Gloss is a markdown variant that concentrates on: minimal, memorable markdown that looks good in the source text; automatic linking to files on your local and intranet storage (these are called FLASH links below); and glossary popups. | |
| IntraMine applies Gloss automatically to .txt files. At present, there is no special extension for Gloss files. | |
| Regular markdown doesn't do links to files on local storage, and editors typically limit automatic linking to the files in your project. With FLASH links, if you want a link to qtcpserver.cpp, and that name is unique across all your local storage, then that's all you have to type to get a link to p:\qt\5.12.5\src\qtbase\src\network\socket\qtcpserver.cpp: the plain file name without any directories or drive or quotes or brackets, or any other adornments. If there are two or more files with the same name, IntraMine picks the one that's closest to where you're typing, based on directory hops up and down to go from one to the other. Paths are selected from among those that you've indicated are "of interest" to you, based on your list of directory paths in data/search_directories.txt. In the rare case where the file name alone is ambiguous, you can add one or more directory names in any order in any sequence to pin down the file you want. You can leave out directory names that don't constrain the instance wanted. And if you need a drive letter to do the job, put it first. | |
| A glossary is arguably a necessity for a project of any size. You've probably seen already how they work in IntraMine: any defined term, such as FLASH links, has a dotted underline in the text, and if you pause your cursor over the term a definition pops up. These are called glossary popups in IntraMine, and in a slightly recursive manner your definitions can also be marked up with Gloss, including FLASH links and styling. For details see "Glossary popups.txt". | |
| IntraMine's Viewer fully implements Gloss, and almost all of Gloss's features are also available in standalone files produced by gloss2html.pl (for standalone Gloss, see "gloss2html.pl for standalone Gloss files.txt"). | |
| IntraMine's Editor shows FLASH links and glossary popups for .txt files. | |
| And most of Gloss is available in ToDo items - see "ToDo.txt#Gloss markdown can be used in ToDo items". The main difference is that links to files must use a full path and be contained in double quotes (eg "C:\folder1\folder2\afile.txt"). | |
| Gloss is for developers (like you) who need to crank out good looking spec, design, test, how-to, development logs, meeting notes, and sundry other documents designed for in-house or personal use. And do so with the absolute minimum of additional markup characters, in a way that's easy to remember. You know, so you'll actually use it. | |
| Gloss processing is fully applied to all .txt files by the Viewer. A subset of Gloss including automatic linking, glossary popups, a synchronized table of contents, and image hovers is also applied to source files. IntraMine's Editor is well suited for editing the source of Glossed files, and shows "live" automatic links and glossary popups. And gloss2html.pl generates the promised fully standalone HTML versions from Gloss sources, either single files or a whole folder at once, with images inlined or as hovers. | |
| Gloss also does | |
• an auto generated and synchronized table of contents (currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL.) | |
• "Headings": h1 h2 h3, done with underlining using at least five =====, -----, ~~~~~. And also h1 h2 etc using "# ", "## " etc at the start of a line. | |
• "Tables": write "TABLE" at the start of a line, put headers on the next line, data on following lines, and separate cells with one or more tabs: the table ends when a line has no tabs. More below, but that's basically it. | |
• "Lists" both numbered and bulleted. | |
• "Emphasis": bold, italic, and | |
• highlighting of any word or short phrase you select, in the text and down the scroll bar. (Due to technical limitations aka my brain size, only single words can be highlighted in CODE/ENDCODE blocks.) | |
• "image hovers": any mention of an image becomes a link to the image, and stopping your cursor over the link will pop up an instant view of the image. If you haven't been using images in your source files, it's because you didn't have image hovers. For text files there's an "Inline Images" button at the top of the Viewer that lets you switch between the default image hovers and fully displayed images. | |
• "Code blocks": if you put some code between CODE and ENDCODE lines it will be styled up a bit. | |
• footnotes and citations, which behave like glossary popups but are restricted to one document and you can put references to them wherever you want. | |
How to | |
Glossary popups | |
| If you pause your cursor over a defined term such as Gloss, a rich definition will pop up. IntraMine supports two glossaries, one for general use when displaying source and text files, and one for use when converting text files to HTML with the Glosser service or the gloss2html.pl Perl program. Glosser was used to generate the HTML version of this document. | |
| For general use: create a glossary_master.txt file anywhere within a folder that's listed for indexing in your data/search_directories.txt file. There's a sample glossary_master.txt file included at the top of your IntraMine folder: open that and follow the instructions at the top to get going. The basic format of a glossary entry is term colon definition, and the definition continues until the next paragraph with a colon. | |
| For generating standalone HTML with gloss2html.pl: use "glossary.txt" as the name of your glossary file, and put it at the top of the folder containing text documents that you want to convert to HTML. The format is the same as for glossary_master.txt files. An example glossary.txt file is included at the top of IntraMine's Documentation folder, and it also has instructions at the top. | |
| "Glossary popups.txt" has slightly more details, with a focus on creating glossary_master.txt files for general use. | |
Table of Contents | |
| Gloss generates a Table of Contents (TOC) automatically for: | |
• headings in text files (see just below) | |
• function, method, class, and struct definitions in source files. | |
| Currently a table of contents is supported for .txt, Perl, Pod, C / C++, Go, JavaScript, CSS, Clojure, Erlang, OCaml, PHP, Python, Ruby, TypeScript, Rust, Java, C#, VBScript(.vb), VB.NET(.vbs), Haskell, Julia, Fortran, COBOL. Alas, non-ASCII definition names are not currently supported in C or C++ or Java and I don't know how to correct that. | |
| The Table of Contents is done alphabetically in source files, and in order of occurrence in text files. | |
| The selected item in the TOC updates automatically to synchronize with the position you're viewing in a document as you scroll. | |
| A little green double-headed arrow doohickey | |
Headings | |
| To mark a line as a heading, underline it with five or more of the same character: equals (=) for top level, hyphen (-) for next level, and tilde (~) for the lowest level. Underlining the first line in a document with ===== will produce the largest heading, by the way. | |
| Heading underline characters |
| Underline with | To get | |
|---|---|---|
| ===== | h2 | |
| ----- | h3 | |
| ~~~~~ | h4 |
| Examples: | |
| Section heading | |
| ================= | |
| produces | |
| Next level heading | |
| ------------------ | |
| produces | |
| Lowest level heading | |
| ~~~~~~~~~~~~~~~~~~~~ | |
| produces | |
Hashed headings | |
| For the sake of compatibility you can also create a heading by putting one or more hashes (#) at the beginning of a line, then one or more spaces or tabs, and then the actual heading text. ### heading produces an h3 heading etc. These work fine for the HTML result, but the effect in the source is reversed from expectations, with more hashes meaning a less important heading. | |
| Note a blank line must precede the # heading line, unless of course it's the first line. This suppresses problems with quoting code from a language where a '#' introduces a comment. If you don't want that: open data/intramine_config_6.txt, and change the value of HASH_HEADING_NEEDS_BLANK_BEFORE to 0. Then restart IntraMine. | |
Horizontal rules | |
| Put three or four equals signs '=' or hyphens'-'or tildes '~' at the beginning of a line, and nothing else on the line, to produce a horizontal rule. A rule done with "===" will be slightly more noticeable than one done with "---" or "~~~". | |
| Since IntraMine uses a monospaced font for text display, horizontal rules can help code examples stand out. | |
| Example: | |
| --- | |
| #special-index-wrapper th { | |
| text-align: center; | |
| } | |
| --- | |
| produces | |
| #special-index-wrapper th { | |
| text-align: center; | |
| } | |
Links | |
| When a source or text file is viewed with IntraMine, local or NAS file mentions within it will be turned into links, provided the file mentioned is in an indexed location. If it isn't, you'll need a full path to get a link. So needless to say indexing all the files you'll be interested in is strongly recommended. For details on how to index folders, see "Configuring folders to index and monitor.txt". | |
| For the details on linking with IntraMine see "FLASH links.txt". | |
Tables | |
Simple tables | |
| Here's a simple Gloss table: | |
| TABLE CodeMirror linkType and class | |
| linkType Class | |
| file cmAutoLink | |
| image cmAutoLinkImg | |
| web cmAutoLinkNoEdit | |
| (internal) cmInternalLink | |
| which displays as | |
| CodeMirror linkType and class |
| linkType | Class | |
|---|---|---|
| file | cmAutoLink | |
| image | cmAutoLinkImg | |
| web | cmAutoLinkNoEdit | |
| (internal) | cmInternalLink |
| To make a simple table: | |
• put "TABLE" at the beginning of a line, optionally followed by a space and a caption | |
• on the next line, put column headers separated by one or more tabs | |
• on the following lines put the data, again with columns separated by one or more tabs | |
• the table ends when there's a line with no tabs. | |
| If you want a blank cell, put a space. No toothpicks |, no pavement _, you don't even have to use enough tabs to make it all line up in the original text (but I know that you will). | |
Cell span and alignment | |
| You can have fancier tables if you want, but of course at the price of having to know and type a bit more. | |
| Put <N> at the beginning of cell contents to indicate how many columns the text should span, where N is an integer. This isn't needed for the rightmost cell, it will take however many columns are remaining to the right. | |
| Put <L>, <R>, or <C> at the beginning of a cell to indicate left, right, or center alignment. Cell text is aligned left by default, except for text spanning multiple cells, which is center-aligned by default. | |
| To combine span and alignment, put the alignment and then span in the '<>' at the beginning of the cell's contents, eg <R3> for text aligned right in a three-column span. | |
| TABLE Column span demo | |
| One Hdr Two Hdr Three Hdr Four Hdr Five Hdr | |
| d11 <3>d12 3 cells d15 | |
| d21 d22 d23 d24 d25 | |
| d31 d32 <L>d33 3 cells left | |
| d41 d42 d43 d44 d45 | |
| <R3>d51 3 cells right d54 d55 | |
| One Hdr | Two Hdr | Three Hdr | Four Hdr | Five Hdr | |
|---|---|---|---|---|---|
| d11 | d12 3 cells | d15 | |||
| d21 | d22 | d23 | d24 | d25 | |
| d31 | d32 | d33 3 cells left | |||
| d41 | d42 | d43 | d44 | d45 | |
| d51 3 cells right | d54 | d55 | |||
| TABLE Cell alignment | |
| Temperature Range in Kelvin | |
| Class Description <R>Low <R>High | |
| <C>O blue <R>30,000 <R>♾️? | |
| <C>B blue white <R>10,000 <R>30,000 | |
| <C>A white <R>7,500 <R>10,000 | |
| <C>F yellow white <R>6,000 <R>7,500 | |
| <C>G yellow <R>5,200 <R>6,000 | |
| <C>K light orange <R>3,700 <R>5,200 | |
| <C>M orange red <R>2,400 <R>3,700 | |
| Temperature Range in Kelvin | ||||
|---|---|---|---|---|
| Class | Description | Low | High | |
| O | blue | 30,000 | ♾️? | |
| B | blue white | 10,000 | 30,000 | |
| A | white | 7,500 | 10,000 | |
| F | yellow white | 6,000 | 7,500 | |
| G | yellow | 5,200 | 6,000 | |
| K | light orange | 3,700 | 5,200 | |
| M | orange red | 2,400 | 3,700 | |
Gloss vs Markdown tables | |
| Here's a simple Markdown style table, in plain old HTML: | |
| <table> | |
| <th> | |
| <td>First header</td><td>Second</td><td>Third</td> | |
| </th> | |
| <tr> | |
| <td>Entry one</td><td>Another entry</td><td>Last entry on first row</td> | |
| </tr> | |
| <tr> | |
| <td>Second data row first cell</td><td>row 2 cell 2</td><td>Last entry in table</td> | |
| </tr> | |
| </table> | |
| And here's the equivalent Gloss table: | |
| TABLE | |
| First header Second Third | |
| Entry one Another entry Last entry on first row | |
| Second data row first cell row 2 cell 2 Last entry in table | |
| which produces | |
| First header | Second | Third | |
|---|---|---|---|
| Entry one | Another entry | Last entry on first row | |
| Second data row first cell | row 2 cell 2 | Last entry in table |
| The HTML version needs 268 characters, and many of them are special. The Gloss table needs 151 characters, of which only five ("TABLE") are at all special. | |
Gloss vs MultiMarkdown tables | |
| Here's a MultiMarkdown table, from | |
| http://fletcher.github.io/MultiMarkdown-5/tables.html | |
| | | Grouping || | |
| First Header | Second Header | Third Header | | |
◦ | :-----------: | -----------: | | |
| Content | ✱Long Cell✱ || | |
| Content | ✱✱Cell✱✱ | Cell | | |
| New section | More | Data | | |
| And more | With an escaped '\|' || | |
| [Prototype table] | |
| ( | |
| Here's the same table in Gloss, as closely as possible: | |
| TABLE Prototype table | |
| Grouping | |
| First Header <C>Second Header <R>Third Header | |
| Content ✱Long Cell✱ | |
| Content <C>✱✱Cell✱✱ <R>Cell | |
| New section <C>More <R>Data | |
| And more With an escaped '|' | |
| Grouping | |||
|---|---|---|---|
| First Header | Second Header | Third Header | |
| Content | Long Cell | ||
| Content | Cell | Cell | |
| New section | More | Data | |
| And more | With an escaped '|' | ||
| MultiMarkdown needs 310 characters, versus 206 for Gloss. | |
| (Note the divider line just above "New section" is produced by a line in the source containing a single tab, which Gloss collapses vertically into a line.) | |
Wider columns | |
| IntraMine's tables rely on the browser to sort out column widths, but sometimes a column can end up being too narrow, especially if the browser window isn't very wide. To force a column to be wider, add spaces or non-breaking spaces at the end of the heading for the column. Regular spaces seem to do the trick too sometimes, but not always. | |
| To type a non-breaking space on a Windows box, hold down the ALT key and type 0160. The numbers 0160 must be typed on the numeric keypad for this to work. And NumLock must also be on. My record for remembering that is, I think, about five years. | |
Lists | |
| You can have unordered (bulleted) or ordered (numbered) lists. | |
Unordered lists | |
• two levels are supported | |
• an unordered list item begins flush left with a '-', '+', or '*'. | |
• optionally you can put one or more spaces at the beginning of the line. | |
◦ if you put two or more of '-', '+', or '*', eg '--' or '+++', you'll get a second-level entry. To make it prettier in the original text, you can insert spaces at the beginning of the line. | |
A top-level or second-level item can continue in following paragraphs. To have the following paragraphs count as part of an item, begin each with one or more tabs or spaces. The leading spaces or tabs will be suppressed in the HTML display. | |
This paragraph begins with three spaces in the source, as does the one before. | |
◦ Another second-level item, with excessive spaces. | |
| To clarify some overlap with horizontal rules: the three or four hyphens '-' for a horizontal rule must be flush left on a line, and followed by nothing else. If there are spaces before the three or four '-' or text afterwards then they count as the start of a second order list item. | |
Ordered lists | |
| An ordered list entry consists of a number and period, or a number period and number, followed by at least one space. There can be spaces or tabs before the first number, but nothing else. | |
| Ordered lists are auto-numbered, provided the following guidelines are followed: | |
1. Two levels, major (2.) and minor (2.4) are supported. Each major entry increments the major number. | |
An item can have more than one paragraph, provided each subsequent paragraph starts with one or more spaces or tabs, and there are no intervening blank lines. The leading spaces or tabs will be suppressed in the HTML display. | |
2. If the first major entry in a list starts with a number, that number is used as the starting number for the list. Minor levels are always numbered starting at 1. | |
2.1 A blank line or regular paragraph that doesn't begin with a space or tab ends the current list and resets numbering. | |
2.2 Any continuation paragraph in the same item will have its leading spaces or tabs suppressed. | |
Here is a second paragraph for item 2.2. | |
And here is a third paragraph, with more leading spaces in the original. Blathering on to make it wrap, blathering on to make it wrap, blathering on to make it wrap. | |
3. '#' can be used as a placeholder, but it's not recommended because if you want to refer to a numbered entry you have to know the number. In practice, careful numbering by hand is more useful. | |
4. If you use two levels, there should be a major level entry starting off each top-level item, such as the "1." "2." "3." entries in 1., 1.1, 1.2, 2., 2.1, 3., 3.1. Without the major items, the major number will not increment. | |
| An ordered list example (a bit messed up in the source to show auto-numbering at work): | |
3. The first major item, with starting number set to 3. | |
3.1 A minor item under 3. | |
3.2 Another minor item, incorrectly numbered as 3.3 in the source (corrected to 3.2) | |
3.3 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.3) | |
3.4 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.4) | |
3.5 Several minor items, carelessly numbered in the source as "#.#" (this will be 3.5) | |
4. The second major item, correctly numbered in source as 4. | |
5. Oops, the source has "6." instead of "5." - this will display as 5. | |
5.1 A minor item, 5.1 (source has 6.1) | |
5.2 A minor items, 5.2 (source has 6.3) | |
5.3 Another minor item. This becomes item 5.3 even though it's "7.1" in the source. | |
| The source for the above example: | |
Emphasis | |
| Put single asterisks (✱) before and after text to mark it as italic. Put two asterisks (✱✱) both before and after text to mark it as bold. You get <em> for italic and <strong> for bold, which I hope is what you expected. | |
| For a short code fragment, you can use ✱!✱let x = 10;✱!✱ | |
| This could use a small example. So I'm going to cheat in the original text and use a Unicode heavy asterisk ✱, which Gloss won't convert. The second instance of the example line uses regular asterisks. | |
| Gloss does ✱italic emphasis✱ and ✱✱bold emphasis✱✱ like this, and code as ✱!✱let x = 10;✱!✱. | |
Gloss does italic emphasis and bold emphasis like this, and code as let x = 10;. | |
Code blocks | |
| Code blocks are supported only in .txt files. To see a code block rendered in HTML open the .txt file using IntraMine's Viewer, or convert a .txt file to HTML using gloss2html.pl and open the result in your browser. | |
| To create a code block in a .txt file: | |
• put CODE on a line all by itself | |
• follow with your lines of code | |
• and finish by putting ENDCODE on a line all by itself. | |
| Here's an example: | |
| (there's an invisible space before "CODE" to block rendering) | |
| CODE | |
| sub InlineJavaScriptForFile { | |
| my ($fileName) = @_; | |
| my $result = ''; | |
| my $contents = ReadTextFileWide($JS_DIR . $fileName); | |
| if (defined($contents) && $contents ne '') | |
| { | |
| $result = "<script type=\"text/javascript\">\n$contents\n</script>\n"; | |
| } | |
| else | |
| { | |
| die("Error, could not load JavaScript file |$fileName|\n"); | |
| } | |
| return($result); | |
| } | |
| ENDCODE | |
| which is rendered in the HTML version of this file as | |
| _STARTCB_FL_ | |
| _STARTCB_sub InlineJavaScriptForFile { | |
| _STARTCB_ my ($fileName) = @_; | |
| _STARTCB_ my $result = ''; | |
| _STARTCB_ my $contents = ReadTextFileWide($JS_DIR . $fileName); | |
| _STARTCB_ if (defined($contents) && $contents ne '') | |
| _STARTCB_ { | |
| _STARTCB_ $result = "<script type=\"text/javascript\">\n$contents\n</script>\n"; | |
| _STARTCB_ } | |
| _STARTCB_ else | |
| _STARTCB_ { | |
| _STARTCB_ die("Error, could not load JavaScript file |$fileName|\n"); | |
| _STARTCB_ } | |
| _STARTCB_ | |
| _STARTCB_ return($result); | |
| _STARTCB_ } | |
| _STARTCB_FL_ | |
| Text in CODE/ENDCODE is given some minimal syntax styling using lolight (https://github.com/lrsjng/lolight), and a light background color. Anecdotally this is sufficient to fool anyone in HR into thinking they're looking at code. | |
Special characters | |
| Gloss makes certain words and strings stand out a bit. With slight exceptions for "=>", and "NOTE" they are emphasized wherever they occur. Here's the list: | |
| and here's how the Viewer displays them: | |
| 🎗TODO | |
| 🎗REMINDER | |
| 🎗REMINDERS | |
| NOTE (if followed by a non-word character such as a space) | |
| 🐝BUG | |
| 🐝BUGS | |
| ☛ (that's "=>", either at the start of a line or preceded by space) | |
| 💡IDEA! | |
| ☑FIXED | |
| ☑DONE | |
| 💩WTF | |
| 🙂 (type a colon ":" followed by a right parenthesis ")", as you already guessed) | |
| And as a special bonus, if you put three or more of @ on a line by themselves you will get a "flourish" image that can serve as a section break. Like so: | |
Standalone is special | |
| For most .txt files, links will be put in for any file specifier that matches an indexed file, and glossary entries will be taken from your collection of glossary_master.txt files. However, there are .txt files that need different handling, namely those that you are using as sources for standalone HTML files, as generated by the Glosser service or the gloss2html.pl Perl program. For those, you want to see glossary entries taken from any glossary.txt file in the same folder, and also limit links to files in the same folder, so there's a match with the resulting HTML version of the file. This happens in both the Editor and Viewer if you have a glossary.txt file in the same folder. | |
Inline HTML | |
| Every now and then you might want something that Gloss can't do out of the box. So now you can put in your own HTML, and it's about as simple as for regular Markdown. | |
How to | |
| To put inline (raw) HTML in your .txt document and have IntraMine's Viewer (and Gloss to HTML) interpret it as HTML: | |
1. Start a line with an exclamation point ! | |
2. Follow immediately with a block-level start tag, typically <div> <p> <table> <ol> <ul> or <pre> | |
3. Put the rest of your HTML, being careful to indent any intermediate end tag that matches the initial start tag | |
4. Put the final end tag flush left on a line by itself. | |
| Here's a contrived example: | |
| !<div> | |
| <div> | |
| <hr> | |
| </div> | |
| </div> | |
| which renders in the HTML version as |
| where you'll notice the first </div> end tag has been indented, that's important. | |
| As an incorrect example, | |
| !<p><em>HELLO!</em></p> | |
| <p>WORLD!</p> | |
| will not display properly because the second, final </p> is not at the start of a line. | |
| Recognized block-level start tags: | |
| p div h1 h2 h3 h4 h5 h6 blockquote pre table dl ol ul script noscript form fieldset iframe math ins del. | |
| If you need some other tag not in the above list, such as the "hr" example above, wrap it in a <div></div> or <p></p> and it will be fine. The fussy details about start and end tags just help with faster parsing and line counting. | |
Where does it work? | |
| Inline HTML as described above works for .txt documents displayed in IntraMine's Viewer and for .txt documents converted to standalone HTML with the Glosser service or the gloss2html.pl Perl program. | |
Custom CSS and JavaScript | |
| You can add custom CSS and JavaScript as well. The CSS and JavaScript will apply to all .txt files displayed with IntraMine's Viewer, and to all .txt files converted to standalone HTML using the Glosser service or the gloss2html.pl Perl program. | |
| To add custom CSS, create css_for_web_server/im_gloss.css (in your IntraMine folder) and put your CSS in there. IntraMine applies <div class="rawHTML"> as a wrapper for all inline HTML, allowing you to restrict your CSS to just the inline HTML. For example, | |
| .rawHTML hr { | |
| border-color: blue; | |
| } | |
| would color up your inline horizontal rules. | |
| To add custom JavaScript that applies to all .txt documents when displayed with the Viewer or converted with the Glosser service etc, create js_for_web_server/im_gloss.js (in your IntraMine folder) and put your custom JavaScript in there. You can put any JavaScript you want, and only IntraMine's displays and Gloss to HTML conversion will make use of it. | |
| Both im_gloss.css and im_gloss.js are in IntraMine's .gitignore file and won't be touched by Git if you pull down a new version of IntraMine. One nuisance is that if you re-clone IntraMine to a new location you'll need to copy the im_gloss.css and im_gloss.js files yourself. | |
| The custom CSS might come in useful now and then, but I can't think of a use for the custom JavaScript. Turning the background light blue every 30 minutes as a reminder to take a short break? An AI prompt? Still, it's there if you want it. | |
Footnotes and citations | |
| Just so we're on the same page, a footnote is generally either an explanation or a citation. And a citation is either a quotation with source, or just a source of something in the main text. You'll find some examples below. | |
| Gloss shows footnote references as superscripts and citation references are shown inline when converted to HTML. That's really the only difference between the two. | |
| To see footnotes and citations as converted to HTML, use IntraMine's Viewer or convert your .txt source file to standalone HTML using IntraMine's Glosser service or the gloss2html.pl Perl program at the top of your IntraMine folder. | |
| As opposed to glossary popups, footnotes and citations apply only within a single document and can be placed freely rather than associated with a particular word or short phrase. Otherwise they're quite similar - in particular, a full footnote or citation will pop up when you pause your cursor over a link to it. | |
| To save words I'll call a footnote or citation a note below. | |
How to make a footnote or citation | |
| To put a note in your source text: | |
• put [^id]: at the beginning of a line, where "id" is one or more letters, numbers, or underscores. For example, "[^1]:" or "[^bignote27]:" | |
• follow with the note | |
• the note ends when there's a blank line | |
• if you want an apparently blank line, put a space or tab on it | |
• most Gloss styling can be used, as described above. However, you can't reference a note inside the body of a note. Linking for standalone HTML is limited in the same way as described for popups in standalone HTML, see "Glossary popups.txt#Standalone is special" - basically, you can link to .txt or .html or image files in the same folder, or any web page. When viewing a .txt file with IntraMine's Viewer, full FLASH links are implemented (as of November 2025) | |
• although you can define a note anywhere in your .txt document, it's best to put them all at the bottom. Line numbers in the HTML version will have skips where the notes were extracted from the main text if you don't put them at the bottom. | |
| Here's an example, with a zero-width space at the beginning of the line to disable processing in the HTML version: | |
| [^99]: here be a footnote. | |
| It's continued on a second line. The following blank line terminates the note. | |
To make a reference to a footnote or citation | |
| Put [^id] in your text anywhere except in a footnote body or inline HTML, where "id" matches the id of the wanted note. | |
| To make a reference to a citation, precede it with a space or tab, as in this [1] is a citation reference. | |
| To make a reference to a footnote, don't put a space or tab before it, as in this on the other hand[2] is a footnote reference. | |
Hover to view a footnote or citation | |
| You can click on the reference link, which will scroll you down to the bottom of the document, but that's old school. Instead, pause your cursor over the link and the note will pop up right there, sparing you the trip. | |
How do footnotes and citations differ? | |
| In the resulting HTML, a footnote is shown superscripted whereas a citation is shown inline. | |
Multiple consecutive note references | |
| Put anything but a space or tab (including nothing at all) between consecutive footnote references[3][4]. | |
| Put a space or tab between citations, eg [5] [6] or [5], [6]. | |
Multiple references to the same note | |
| It's the digital age, so this is allowed. As an example here, [1] and[2] repeat references made just above. | |
Footnote and citation numbering | |
| Footnotes and citations will be renumbered automatically in the same sequence as references are encountered in the text. Examples above have been numbered in sequence 1 2 3 to avoid confusion when comparing the .txt and .html versions. Here's another footnote[7] which will probably become footnote 7 here even though the id in the source text is "biggy29". | |
| This does have the drawback though that you can't be sure of the footnote numbers until you view an HTML version. | |
Reference with no note | |
| If a note reference in the text has no corresponding note definition it will not be shown as a link. | |
Note with no reference | |
| If a footnote or citation is never referenced in the text then it will not appear in the HTML version. That's mainly to avoid awkward questions. | |
HTML display | |
| Your note references will be shown as links, with the "^" removed. Footnote references will be superscripted in a slightly smaller font size, citation references will be shown inline in the same size as the text. | |
| Footnotes and citations will all be gathered together at the bottom following a horizontal rule. The note numbers will be bold flush left, and the body of the note will be indented slightly after the first line. | |
| There is no difference in the display of the body of footnotes versus citations. | |
A suggestion | |
| Put all your footnote or citation bodies at the bottom of your source .txt, they will be easier to find and won't disturb the line numbers in the resulting HTML version. | |
| Let's end with a more elaborate footnote that very briefly summarizes this document[8]. | |
What Gloss doesn't do | |
| Gloss is intended mainly for in-house documentation, and developer logs. So there are some things you might expect (by comparison with Markdown for example) that you won't find in Gloss. | |
| Item | Why | |
|---|---|---|
| ~~strikethrough~~ | I have never needed that, have you? | |
| Definition list | Gloss provides glossary popups instead. A definition is available wherever a term is used, by stopping the cursor over the term. | |
| Heading ID | Gloss links headings automatically: put the heading mentions in double quotes, for example "Overview". | |
| Alt text for images | Gloss pops up a view of the image when you put your cursor over the image name. If alt text is needed, you can type it before or after the image name. | |
| Blockquote | Put it in quotes and italicize the author, good enough for most uses. | |
| Task list | Task lists are everywhere. For example, IntraMine's ToDo page🙂 |
| Gloss does do hashed headings, such as #### This is an h4 heading, but underlining with five or more of = - or ~ just looks better in the original. Adding more and more characters to a line shouldn't make the resulting text smaller and smaller. | |
| And one last important thing omitted is the line as a unit of comprehension. In a formatted text document there are words and sentences and paragraphs as units of comprehension, but arguably not lines. In Gloss when you press Enter you end a paragraph, not a line, and line wrap keeps all the text visible. As a nice side effect of this approach, Gloss requires absolutely no extra blank lines anywhere (except to separate footnote bodies). | |
| contents.html | |
1. A citation example. Note it's followed by a blank line to end the note. ↩ |
2. A footnote. Exactly the same as a citation body. Also followed by a blank line to end the note. ↩ |
3. A second footnote, numbered three in the HTML display. ↩ |
4. A fourth footnote. ↩ |
5. A citation for the consecutive citations example. ↩ |
6. And another citation for the consecutive citations example. ↩ |
7. A footnote with id "biggy29" in the source .txt, probably renumbered automatically to 7 in the HTML display. There is no need for a blank line after the last note. ↩ |
8. Gloss: IntraMine's Markdown variant, minimal memorable markup designed for intranet use. You can use it fully in text files and use FLASH links in source files, as described in "Gloss.html". Gloss can also be used in glossary definitions which show in any text or source file, see "Glossary popups.html" for glossary usage. |
| A sample table (see "Gloss.html#Tables" for details) |
| Feature | IntraMine Viewer, text | Viewer, source | Glossary popups | ToDo |
|---|---|---|---|---|
| Bold, italic, code | Yes | No | Yes | Yes |
| FLASH links | Yes (full support) | Yes | "Quotes needed" | "Quotes" and full path needed |
| Image hovers | Yes | Yes | No (inlined) | "Quotes" and full path needed |
| Tables | Yes | No | Yes | Yes (use tab or \t to separate cells) |
| Lists | Yes | No | Yes | Yes |
| CODE blocks | Yes | No | No | No |
| (A TABLE ends when there's a line with no tab.) |
| Quotes can be single or double, eg "Gloss.html" or 'Gloss.html'. |
| IntraMine's Editor fully supports FLASH links, image hovers, and glossary popups, but otherwise shows Gloss markup as typed. |
| You can also have |
1. Numbered lists |
1.1 with subitems, up to 99.99 |
• bulleted lists |
◦ with subitems too |
Bold, italic, and /* Code snippets */ int x = 42;. |
| Images will be shown inline, eg |
| 🙂 ↩ |